<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
  <head>
    <title>Using Rational Purify with CIAO</title> 
    <!-- $Id$ -->
  </head>
  <body>
    <h1>Using Rational Purify with CIAO</h1>
    <p>This document is about using Purify with Visual Studio 7.1 to track down 
      memory leaks and other bugs in CIAO applications. For the Linux/Unix 
      environment, Valgrind is a better-suited tool - see Will Otte's documentation 
      on using Valgrind with CIAO in this directory.</p>
    <p>Purify can be run from within Visual Studio, or standalone. The executable is 
      c:\Program Files\Rational\PurifyPlus\purifyw.exe. Typing this will bring up the 
      same Purify window you see if you run it from within Visual Studio. You can 
      install Purify from the web by going to <A href="file://\\Atlantis\software\RationSuiteEnterprise-v2003-06-12">
        \\Atlantis\software\RationSuiteEnterprise-v2003-06-12</A> &nbsp;and clicking 
      on <code>C57BPML.zip</code>. This will install a whole bunch of Rational stuff 
      by default, so you will probaby want to deselect everything but PurifyPlus, 
      although Quantify is a good bottleneck-finder when you're trying to improve 
      performance, so that might be worth installing and playing with as well. During 
      the installation process, you'll be prompted for a mode of licensing. Select 
      the use of a license server, and then you'll be prompted for its address. Use <code>
        rational.vuse.vanderbilt.edu</code>.</p>
    <p>The option to exclude all modules in Windows directories will probably be set 
      by default, but if you notice memory leaks reported for Windows stuff, you 
      might want to double check this and turn it off. From the PurifyPlus menu bar 
      item in Visual Studio, it's at <b>PurifyPlus-&gt;Purify-&gt;Settings-&gt;DefaultSettings-&gt;PowerCheck</b>. 
      When run for the first time, Purify will instrument all libraries linked to the 
      executable. Select <b>PurifyPlus-&gt;Purify-&gt;Run</b>, and a window will pop 
      up prompting you for the executable name, command line options, and working 
      directory.</p>
    <p>Purify's output will appear in the Visual Studio text editing window. This 
      output can be saved to the given filename. The type of error reported is 
      indicated by a 3-letter code - the most common are UMR (Unitialized Memory 
      Read), FMM (Freeing Mismatched Memory), and MLK (Memory Leak). Each of these 
      can be expanded to show the call stack. The depth of the call stack can be 
      modified in Settings if it's not deep enough. FMM messages will show both 
      allocation and deallocation call stacks.</p>
    Quite often in CIAO, we will want to Purify a process that is spawned by 
    another process, and therefore not directly runnable in Purify. This is fairly 
    easy to do, but it must be done from the command line. If the name of the child 
    process we want to instrument is <code>child.exe</code>, then it can be 
    instrumented by typing
    <br>
    <code>purifyw /Run=no /Replace=yes child.exe</code><br>
    This will rename the original executable as <code>child.exe.Original</code>, 
    and the new instrumented executable will be <code>child.exe</code>. Now when 
    you run the parent process under Purify, you'll see one window opened up in 
    Visual Studio's text editor for this process, and when the child process is 
    spawned, a second window will open. A couple of caveats to make this work 
    smoothly:
    <ul>
      <li>
        Instrumented executables run 2 to 5 times slower than uninstrumented ones, so 
        any timeouts in the code should be extended accordingly. For example, if an 
        instrumented NodeApplication is spawned by NodeManager, add <code>-d 15</code> or
        <code>-d 20</code>
      to NodeManager's command line.
      <li>
        If an instrumented process is simply killed, there will probably be many 
        spurious error messages, mostly related to ORB resources that were not cleaned 
        up by a graceful shutdown. All processes tested with Purify should have a 
        graceful shutdown built in to eliminate these bogus memory leak messages.
      </li>
    </ul>
    <hr>
    <address>Jeff Parsons</address>
    <!-- hhmts start --> Last modified: Oct&nbsp;3 2005 
    <!-- hhmts end -->
  </body>
</html>
